Celestin Apprentice 5/Apprentice-Release5.iso/Utilities/Programming/EnterAct 3.7.3/Documentation/EnterAct in brief

Text File | 1996-06-15 | 20.3 KB | 476 lines | [TEXT/KEEN]

*********EnterAct in brief (this is not the manual) *************
-----------
Introduction
-----------

EnterAct is a full C/C++/Java project-oriented editor, with
additional code definition display capabilities. And then some.

To use EnterAct with Java source, please see "Adding Java files"
below (<option>click in the title bar for a popup menu).

 Most of EnterAct's best features work with first-draft,
 uncompilabe code. As long as the delimiters balance and
 the key words are not too badly misspelled, EnterAct will
 provide instant definition and prototype display, a class
 browser, jumping to definitions, cross-referencing etc.

 EnterAct typically needs 4-8 Meg for medium to large projects.
 Sorry, that's the price of power.

---------------
Necessary things
---------------

    Installation
Put EnterAct 3 and the "Drag_on Modules" folder next to the
folder that holds the mac toolbox headers you wish to use the most:
• Symantec: next to the THINK Project Manager
• Metrowerks: next to the compiler you're using
• MPW: next to the "Interfaces" folder.

To access either THINK Ref or QuickView, put a "(Tools)" or "Tools"
folder next to EnterAct and drop an alias of THINK Ref or QuickView
(or both) into it. Commands to access these appear at the bottom
of the Search menu.

To access the AppleScripts supplied with EnterAct, put the
"(EnterAct Scripts)" folder next to EnterAct.

To use code templates, put the "EnterAct Code Templates" file
next to EnterAct.

    Adding Java files
Java files should go in the left pane of your project. To put your Java
files in the right place, select "File Extensions..." from the "EnterAct"
menu and type in "java" as an extension for the left pane. If you do
this with no project open, this will affect all new projects.

Otherwise, everything for Java files is the same as for C++ files.
For best results, grab the source for the standard java libraries
somewhere (eg CW9) and add it to your project.

    Making a new project
Select "New Project" (this same dialog appears when you start up
EnterAct and cancel the "Open Project"dialog). Give your project a
name, and save it.

In the subsequent "Select <system> Folder..." dialog that appears,
select the folder that holds your system <header> files. If you
have placed EnterAct within a folder that also holds these files,
you can just Cancel.

Add files with the "Add Files..." or "Add All in Folder..." commands -
hold down the <Shift> key and the latter becomes "Add All in
Subfolders...". With the "Add All" commands, use the button at the
bottom of the dialog to add whole folders at once (including all
files in subfolders if the <Shift> key was down).

To add all toolbox headers, pick "Add Mac Headers".

Add as many or as few files as you want, regardless of whether
they make up a complete project. Neglect not non-source files
(spec, design etc) which end up in the rightmost project window
pane. Source files are in the left pane, headers in the middle. To
force files with nonstandard extensions into particular panes, use
"File Extensions...." to enter the selection and pick the pane.

Note that things work best if you include definitions for all the
names in your source code, especially toolbox terms but also
PowerPlant or TCL, and ANSI headers etc.

NOTE if a folder's name is in parentheses, the files in it will not
be added to your project. To exclude a folder such as "Old Source",
change its name to "(Old Source)".

If you add more than one file with the same name, truncated full
path names will appear to the right of the file name, to help you
tell which file is which. (See "Building a project dictionary" just
below to exclude files from being built into your dictionary).

The project window responds to many keys in standard ways.
Go left and right across the three panes with the left and right
arrow keys, <Command><down arrow> to go to the bottom of a
pane etc. To type your way to a particular file, you can type
the first part of the name or any distinctive part of the name
(useful if you have a lot of files whose names all begin with the
same prefix, eg to advance to "PROJECT7_Mouse.c" you could
probably type just "mou").

You can open a file from your project window by double-clicking
on it, or hitting <Return>, or use "Go to..." with the name selected.
In all cases, the project window itself will go all the way to the back.

Please add this file to your project for handy reference (use "Add
Front File"), and add the "EnterAct 3 Manual" as well - eventually,
you'll want to browse through it.

    Building a project dictionary
To exlude a file from being built into your dictionary, hold down
the <Command> key and click on its name in the project window.
A dash '-' will appear to the left of its name, meaning your
dictionary will be "minus" that file.

Select "Update Dictionary". If you run into a problem, see
«EnterAct 3 Manual» 126.
(click in the line above and select "Go to..." from the Search menu -
if you've added the manual to your project, this will open the
manual and take you to the line.)

Now and then (typically when lookup doesn't give expected
results) issue an "Update Dictionary" to keep your
dictionary current. Your dictionary tracks everything defined
outside of function bodies, so if you add a member to a class
or define a new method, your dictionary will be "out of date".
On an 040 machine running at 25 Mhz an incremental update
takes about 6 secs, a nice little "mini-break".


    Looking up definitions
The AutoLook window is EnterAct's reason for being, so please
try it out!

For any sort of lookup to work, you must have a project with
built dictionary open.

Select "AutoLook": when you double-click on or click after a C/C++
or Java name in any window, the AutoLook window will display its
definition. This includes all names for structs, unions, enums,
enum constants, functions, methods, classes, file or global scope
variables, defines, and data members, basically everything that
is defined outside of a function body.

The AutoLook window can also display definitions of local
variables. For this to work, the file in question must be a
source file (ie its name must end in .c or cp etc) and if
you've just created a function you should save the file.
Clicking after a local variable name will then produce a
definition in the AutoLook window.

AutoLook is less accurate in non-source windows, but it still
works.

As of v3.5, AutoLook provides fast extremely accurate lookup for
data member and method names, even in complicated "reference
chains" such as "mObject->SomeMethod().aMember[i].whatsIt"
--just click after any name and the AutoLook window will show
you what it is, or make very good guesses in the rare cases when
the method's context doesn't provide enough scope resolution,
or your spelling is wrong.

For a more permanent separate display of the definition, press the
<Enter> key. A separate lookup window will appear. Hold down the
<Option> key and drag in the lookup window's title bar to select the
exact definition you want from a popup menu. Note that local
variables are at present excluded, you'll have to Copy and Paste
from the AutoLook window if you want a separate view of them.
(Tip: for local variables, click after the type name for the variable
in the AutoLook window, and press <Enter> to pop up a separate
window showing the definition.)

To look up the struct or class containing a particular member,
again double-click on or click to the right of the name, and press
<Shift><Enter>. A lookup window will appear, holding struct or
class definitions that contain the member. There will often be
several, so use the lookup window's popup menu as described just
above to pick the one you want. The AutoLook window
will usually display the definition you want as soon as you click
to the right of the name, so this isn't much needed unless you
want a separate display of the definition.

To use EnterAct as a lookup aid while working mainly with
some other editor: have a relevant EnterAct project open,
dictionary built, AutoLook open and frontmost; in the other
editor, Copy the term you want looked up, and switch to
EnterAct. If the definition does not immediately appear in
the AutoLook window, press <Commmand><Enter>. If it was
a member name and you want the full definitions of the containing
structs or classes, press <Shift><Command><Enter>.

All lookup windows including AutoLook are fully editable but
cannot be saved.

    Browsing
Select "Browse" from the EnterAct menu. Browse as in THINK C.
Click and <Shift>click on and off of class names to show/hide
multiple inheritance lines. (As mentioned, class browsing works
with first-draft code.)

To view a particular class, type the first part or some distinctive
part of its name.

If a class "uses" or "has" member classes, these will be listed
below the main class name, separated from it by a white line.
You can also double-click on these names to jump to their
definitions, or click-and-hold to select one of their method
names from a popup.

The multiple inheritance lines often aren't enough, so if you
<Option> click on a class name you'll see a popup
listing all of the classes from which it is derived. If you let
go the mouse while over one of these base class names you'll
jump to its definition.

If you <Command> click on a class name the resulting popup
will show not only all methods in the class but all methods it
inherits. Note if it's an ENORMOUS list of methods, it make take
5 seconds for the popup to show-please be patient the first
few times you try this.

In all method popups, virtual methods are marked with a "v" so
you can tell at a glance if a method wants or needs or has an
override.

Summary of class popups:
• click on a class name: all methods defined by the class
• <Command> click: all inherited methods too
• <Option> click: the immediate parents of a class.

    Finding Definitions
Single words: <Option>double-click.

Full method names (eg "TCircle::Draw") : select the full name
and use "Find Definition". Or, <Option>double-click on one word,
drag to the other, and release.

Just the method name (eg "Draw") :  normally the AutoLook
window will show just the one you want, but even if it
show several you can jump to it by <Option>double-clicking
on the full method name in the AutoLook window.

If the AutoLook window doesn't show the one you want,
press <Enter>; a lookup window appears holding full
prototypes for all methods with that name; use the lookup
window's popup menu to pick the one you want; then jump
to it as described above for full method names.

More than one definition for a term:
press <Enter> to look the name up; use the popup menu in the
lookup window to pick the definition you want (<Option> click
in the window's title bar); and then use <Option>double-click on
the name, or "Find Definition" without changing the default
selection. The popup menu includes truncated full path names
for the defining files, so you can tell which definition is which.

Static functions and variables: if you're in the file where it is
defined, just <Option>double-click on the name. If you have
several definitions of such a name and you aren't in the file where
it is defined, use the approach for more than one definition described
just above.

    Multi-file search
The Find dialog contains buttons to select all files of a particular
type in the project window. Files selected for multi-file
operations (including searching) have bullets (•) to their left in
the project window. To "fine tune" your multi-file selection, hold
down the <Option> key and click or drag right in the project
window.

The "Batch" check box generates a list of all lines where the search
string can be found in your multi-file selection. To jump to the
file and line indicated for one of the finds, click on the line and
use "Go to...".

Multi-file selections have other uses, such as "Remove •'d files",
input for several "Index" commands, and input for hAWK programs
(see the «hAWK User’s Manual»).

Placing a dash '-' beside a project file name indicates that it
should be excluded when building your dictionary, but it's often
the case that you don't want to search those files either.
In the Find dialog, the "Skip '-'" checkbox allows you to exclude
files marked with a dash '-' in the project window when doing
a multi-file operation such as searching.  Please note this
checkbox affects all other buttons in the Find dialog, and all
operations done with the file list. Specifically, the All and
None buttons don't touch files marked with a dash '-' if the
"Skip '-'" checkbox is checked, and such files aren't passed to
a hAWK program, or looked at when you click "Find In Next File".

The "Dual Batch Find" button in the Find dialog calls up a separate
(modal alas) dialog that lets you search for two search strings
that occur within a certain number of lines or characters of each
other. Clicking OK fires off a search of your bulleted files, with
results of the search presented in a text window. "Zero" lines
means on the same line, and a separation of zero characters means
the two strings must occur together with no characters between
(as in "Cmd" and "Handle" matching "CmdHandle" or "HandleCmd").
Dual Batch Find obeys your "Match Words" and "Ignore Case"
settings in the main Find dialog.

    Accessing THINK Reference
Beside EnterAct at the same level, have a folder entitled "Tools"
or "(Tools)"; drop an alias of THINK Reference in this folder.

To look up THINK Ref's thoughts on a term, select it or click
to the right of it and issue "Find in THINK Reference" (<cmd><->).

    Accessing Toolbox Assistant
As for THINK Ref, but drop an alias of "QuickView" in your
Tools folder. The "Find in Toolbox Assistant" command is
at the bottom of the Search menu (<cmd><4>).

    Editing and Undo
All basic editing commands are undoable, with a single level
of undo. This includes Replace All.

As you work, EnterAct logs all of your activities (including
contents of edits) to the "EnterAct Recent Activities" file. In a
pinch, you can recover the contents of a delete or remind yourself
of what you just did by selecting "Show Activities..." from
the Edit menu.

Well, not all of your activities, only the last ten thousand.

See «EnterAct 3 Manual» 4638 for a new and nicer way to cut
and paste blocks of code. (To go there: add this file and the
EnterAct 3 Manual to an EnterAct project, then click anywhere
in the first line of this paragraph and use the "Go to" command,
<cmd><,>).

    Working with Code Warrior
By default, when you open a document and Code Warrior also
has the document open, EnterAct will force Code Warrior to
close and save the file before opening it, asking you first of
course before doing so. To turn this off,
deselect the "Safe switching under MultiFinder" option
in the Options... dialog (under the Edit menu). Having this
option on also means that EnterAct will save all your
documents when you switch out, and refresh them from
disk when you switch back if they have been changed by
some other application.

    The Locations Menu
Select "Add Current Location" to add a sort of "global marker" to
the Locations menu for your current location. This is project
independent, though note the position will not be maintained
if you edit the corresponding source file with another editor.
The text you have selected when you use the Add Current Locations
command will be entered as the default name of the position in
the dialog that subsequently appears: you can edit this name, or
use no name at all and EnterAct will make up a name for you.

To remove a location from this menu:
• go to the location (typically by picking it from the Locations menu)
• select Delete Current Location from the Locations menu.

If the location does not exist any more, when you pick it from
the Locations menu you will be told it can't be found, and asked if
you want to delete it from the menu.

You can have up to 10 different locations under this menu.

    Code Templates
Great fun. All templates are stored in the text file "EnterAct
Code Templates", which is very easy to modify (please take a look
at it). Add this file to the folder where you keep EnterAct, at the
same level.

To use a template, you type its name and press <command><return>.
And <command><return> will also advance you to the next logical
insertion point in your template (or in any code for that matter). If
you save changes to your "EnterAct Code Templates" file using
EnterAct, your new templates are instantly available (no need to
quit and restart). Templates don't have to contain code, and
template names can contain any non-blank characters, not just
letters and numbers.

Each entry has the form
ENTRY
entry_name
arbitrary text
    making up the definition
    of the entry
END

For the complete details on code templates, see the top of
the "EnterAct Code Templates" file. If you'd like to try one
now and you're using EnterAct, open a new window and type

html<command><return>


Keep all your entries flush-left, and EnterAct will adjust your
indentation when pasting your template in. Just open up a new line
and tab in to the right position before typing the entry name and
pressing <command><return>.

Tip: add "EnterAct Code Templates" to your "Locations" menu so you
can change your templates on the fly.

-----------------
Other useful things
-----------------
You can Balance a delimiter by double-clicking on it.

EnterAct comes equipped with hAWK, a version of AWK. It really
is "three clicks and Run", with many supplied programs. See the
«hAWK User’s Manual» for details. You can also fire off a hAWK
program by using a command line, and you can save the command
line as a "code template" in the "EnterAct Code Templates" file.
If you'd like to try one now and have fully installed EnterAct,
open up a new window and type the word "time", then hit
<command><return> twice. The first <command><return> expands
"time" into a hAWK command line, and the second <command><return>
runs the corresponding hAWK program. Neat, eh?

EnterAct's <Enter>-driven lookup tolerates many kinds of spelling
and (more importantly) memory errors. When in doubt, give it your
best guess and press <Enter>. For extreme cases, use the "Options"
dialog to increase the "Number of entries per lookup window" to 20.
For emergency use only, use <Option><Enter> instead of plain <Enter>
to fire up EnterAct's most error tolerant definition retriever - be
prepared for some wild guesses mixed in there with the good ones!

To look up the last word on the clipboard, typically copied while in
another application, press <Command><Enter>. Note if you have
the AutoLook window open it will automatically show a definition
for a word on the clipboard as you switch back to EnterAct.

"Go to..." is very general. It accepts line numbers, file names, marker
names, and combinations such as file name/marker name, file
name/line number. Handy for placing references in code files to
supporting documentation. Moderately error tolerant, full correct
spelling not required. To see it work, add the "EnterAct 3 Manual" to
your project if you haven't done so, then click anywhere on the
following line and "Go to":
«EnterAct 3 Man» «17   “Go” cmds»

The European-style quotes «» are helpful in most "Go to" link names;
to generate these painlessly, see
«EnterAct 3 Man»  6233 (any individual mark)
and
«EnterAct 3 Man» 7775 (marks in documentation files especially)

To open an included file, click on the line in your source where it's
included and use "Go to".

EnterAct projects accept PICT files.

Printing doesn't clip off long lines, it wraps them around.

EnterAct can be used as the THINK Project Managers's editor,
as explained in either the THINK or EnterAct manuals.

When EnterAct can't locate a project file, and you have enabled
the "Relocate files automatically" option,  it starts searching
at the top of the disk where the file was last seen and
searches down until it finds it (or not). Renaming or moving
a folder does not affect EnterAct's memory of where a file is.
Activating the "Relocate files automatically" option is NOT
recommended, unless you're absolutely sure all your files
have unique names.

If you have favorite AppleScripts to compile projects etc, drop
them in the (EnterAct Scripts) folder for easy access.
The scripts must be compiled scripts, not just text-only.
They should do something simple and straightforward, and then
quit, since you won't be able to continue working in EnterAct
until the script finishes.

That's more than enough to get going. If you become inordinately
fond of EnterAct's definition lookup capabilities, be sure to read
through the full manual for details on the above features and a
host of others.